home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / coleitr.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  13KB  |  335 lines
  1. /*
  2. *****************************************************************************************
  3. *                                                                                       *
  4. * COPYRIGHT:                                                                            *
  5. *   (C) Copyright Taligent, Inc.,  1996                                                 *
  6. *   (C) Copyright International Business Machines Corporation,  1996-1999               *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.                  *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure             *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                              *
  10. *                                                                                       *
  11. *****************************************************************************************
  12. */
  13. //===============================================================================
  14. //
  15. // File coleitr.h
  16. //
  17. // 
  18. //
  19. // Created by: Helena Shih
  20. //
  21. // Modification History:
  22. //
  23. //  Date         Name          Description
  24. //
  25. //  8/18/97     helena      Added internal API documentation.
  26. // 08/03/98        erm            Synched with 1.2 version CollationElementIterator.java
  27. //===============================================================================
  28.  
  29. #ifndef COLEITR_H
  30. #define COLEITR_H
  31.  
  32.  
  33. #include "unistr.h"
  34. #include "tblcoll.h"
  35. #include "chariter.h"
  36.  
  37.  
  38. class Normalizer;
  39. class VectorOfInt;
  40. class VectorOfPToContractElement;
  41.  
  42. /**
  43.  * The CollationElementIterator class is used as an iterator to walk through
  44.  * each character of an international string. Use the iterator to return the
  45.  * ordering priority of the positioned character. The ordering priority of
  46.  * a character, which we refer to as a key, defines how a character is
  47.  * collated in the given collation object.
  48.  * For example, consider the following in Spanish:
  49.  * <pre>
  50.  * .       "ca" -> the first key is key('c') and second key is key('a').
  51.  * .       "cha" -> the first key is key('ch') and second key is key('a').
  52.  * </pre>
  53.  * And in German,
  54.  * <pre>
  55.  * .       "æb"-> the first key is key('a'), the second key is key('e'), and
  56.  * .       the third key is key('b').
  57.  * </pre>
  58.  * The key of a character, is an integer composed of primary order(short),
  59.  * secondary order(char), and tertiary order(char).  Java strictly defines
  60.  * the size and signedness of its primitive data types.  Therefore, the static
  61.  * functions primaryOrder(), secondaryOrder(), and tertiaryOrder() return int32_t
  62.  * to ensure the correctness of the key value.
  63.  * <p>Example of the iterator usage: (without error checking)
  64.  * <pre>
  65.  * .  void CollationElementIterator_Example()
  66.  * .  {
  67.  * .      UnicodeString str = "This is a test";
  68.  * .      UErrorCode success = U_ZERO_ERROR;
  69.  * .      RuleBasedCollator* rbc =
  70.  * .          (RuleBasedCollator*) RuleBasedCollator::createInstance(success);
  71.  * .      CollationElementIterator* c =
  72.  * .          rbc->createCollationElementIterator( str );
  73.  * .      int32_t order = c->next(success);
  74.  * .      int32_t primaryOrder = CollationElementIterator::primaryOrder( order );
  75.  * .      delete c;
  76.  * .      delete rbc;
  77.  * .  }
  78.  * </pre>
  79.  * <p>
  80.  * CollationElementIterator::next returns the collation order of the next
  81.  * character based on the comparison level of the collator.  A collation order 
  82.  * consists of primary order, secondary order and tertiary order.  The data 
  83.  * type of the collation order is <strong>int32_t</strong>.  The first 16 bits of 
  84.  * a collation order is its primary order; the next 8 bits is the secondary 
  85.  * order and the last 8 bits is the tertiary order.
  86.  *
  87.  * @see                Collator
  88.  * @see                RuleBasedCollator
  89.  * @version            1.9 1/30/97
  90.  * @author             Helena Shih
  91.  */
  92. class U_I18N_API CollationElementIterator
  93. {
  94. public :     
  95.     /**
  96.      * NULLORDER indicates the iterator has consumed the last element.
  97.      */
  98.     static  int32_t const   NULLORDER;
  99.  
  100.     /** Destructor
  101.      */
  102.                                 ~CollationElementIterator();
  103.     /**
  104.      * Returns true if "other" is the same as "this"
  105.      */
  106.     virtual     bool_t          operator==(const CollationElementIterator& other) const;
  107.  
  108.     /**
  109.      * Returns true if "other" is not the same as "this".
  110.      */
  111.     virtual     bool_t          operator!=(const CollationElementIterator& other) const;
  112.  
  113.     /**
  114.      * Resets the cursor to the beginning of the string.
  115.      */
  116.             void                reset(void);
  117.     /**
  118.      * Gets the ordering priority of the next character in the string.
  119.      * @param status the error code status.
  120.      * @return the next character's ordering.  Returns NULLORDER if
  121.      * the end of string is reached.
  122.      */
  123.             int32_t             next(UErrorCode& status);
  124.      /**
  125.       * Get the ordering priority of the previous collation element in the string.
  126.       * @param status the error code status.
  127.       * @return the previous element's ordering.  Returns NULLORDER if
  128.       * the beginning of string is reached.
  129.       */
  130.             int32_t                 previous(UErrorCode& status);
  131.  
  132.     /**
  133.      * Gets the primary order of a collation order.
  134.      * @param order the collation order
  135.      * @return the primary order of a collation order.
  136.      */
  137.     static  int32_t             primaryOrder(int32_t order);
  138.     /**
  139.      * Gets the secondary order of a collation order.
  140.      * @param order the collation order
  141.      * @return the secondary order of a collation order.
  142.      */
  143.     static  int32_t             secondaryOrder(int32_t order);
  144.     /**
  145.      * Gets the tertiary order of a collation order.
  146.      * @param order the collation order
  147.      * @return the tertiary order of a collation order.
  148.      */
  149.     static  int32_t             tertiaryOrder(int32_t order);
  150.     /**
  151.      *  Return the maximum length of any expansion sequences that end
  152.      *  with the specified comparison order.
  153.      *  @param order a collation order returned by previous or next.
  154.      *  @return the maximum length of any expansion sequences ending
  155.      *          with the specified order.
  156.      */
  157.         int32_t                    getMaxExpansion(int32_t order) const;
  158.  
  159. public:
  160.     /**
  161.      *  Gets the comparison order in the desired strength.  Ignore the other
  162.      *  differences.
  163.      *  @param order The order value
  164.      */
  165.            int32_t              strengthOrder(int32_t order) const;
  166.     /**
  167.      * Sets the source string.
  168.      * @param str the source string.
  169.      * @param status the error code status.
  170.      */
  171.             void                setText(const   UnicodeString&  str,
  172.                                                 UErrorCode&      status);
  173.      /**
  174.      * Sets the source string.
  175.      * @param str the source character iterator.
  176.      * @param status the error code status.
  177.      */
  178.             void                setText(CharacterIterator&  str,
  179.                                         UErrorCode&            status);
  180.    /**
  181.      *  Checks if a comparison order is ignorable.
  182.      *  @param order the collation order.
  183.      *  @return TRUE if a character is ignorable, FALSE otherwise.
  184.      */
  185.     static    bool_t              isIgnorable(int32_t order);
  186.     /**
  187.      *  Gets the offset of the currently processed character in the source string.
  188.      *  @return the offset of the character.
  189.      */
  190.             UTextOffset          getOffset(void) const;
  191.     /**
  192.      *  Sets the offset of the currently processed character in the source string.
  193.      *  @param newOffset the new offset.
  194.      *  @param status the error code status.
  195.      *  @return the offset of the character.
  196.      */
  197.             void                setOffset(UTextOffset newOffset,
  198.                                           UErrorCode& status);
  199. protected:
  200.     /**
  201.      * CollationElementIterator constructor.  This takes the source string and
  202.      * the collation object.  The cursor will walk thru the source string based
  203.      * on the predefined collation rules.  If the source string is empty,
  204.      * NULLORDER will be returned on the calls to next().
  205.      * @param sourceText the source string.
  206.      * @param startOffset the beginning offset of the string where the cursor
  207.      * starts the iterating.
  208.      * @param endOffset the ending offset of the string where the cursor
  209.      * stops the iterating.
  210.      * @param order the collation object.
  211.      */
  212.                                 CollationElementIterator(   const   UnicodeString&  sourceText,
  213.                                                             const   RuleBasedCollator*  order,
  214.                                                             UErrorCode& status);
  215.  
  216.     /**
  217.      * CollationElementIterator constructor.  This takes the source string and
  218.      * the collation object.  The cursor will walk thru the source string based
  219.      * on the predefined collation rules.  If the source string is empty,
  220.      * NULLORDER will be returned on the calls to next().
  221.      * @param sourceText the source string.
  222.      * @param startOffset the beginning offset of the string where the cursor
  223.      * starts the iterating.
  224.      * @param endOffset the ending offset of the string where the cursor
  225.      * stops the iterating.
  226.      * @param order the collation object.
  227.      */
  228.                                 CollationElementIterator(   const    CharacterIterator&  sourceText,
  229.                                                             const   RuleBasedCollator*  order,
  230.                                                             UErrorCode& status);
  231.     /**
  232.      * Assignment operator
  233.      */
  234.     const   CollationElementIterator&
  235.                                 operator=(const CollationElementIterator& other);
  236. public:
  237.     /**
  238.      * Copy constructor.
  239.      */
  240.                                 CollationElementIterator(const  CollationElementIterator& other);
  241.     //============================================================
  242.     // privates
  243.     //============================================================
  244. private:
  245.     /**
  246.      * Default constructor.
  247.      */
  248.                                 CollationElementIterator();
  249.     /**
  250.      * Copy constructor.
  251.      */
  252.                                 CollationElementIterator(const RuleBasedCollator* order);
  253.  
  254.     /**
  255.      * Gets the ordering priority of the next contracting character in the
  256.      * string.
  257.      * @param ch the starting character of a contracting character token
  258.      * @param status the error code status.
  259.      * @return the next contracting character's ordering.  Returns NULLORDER
  260.      * if the end of string is reached.
  261.      */
  262.             int32_t             nextContractChar(   UChar     ch,
  263.                                                     UErrorCode&  status);
  264.  
  265.     /**
  266.      * Gets the ordering priority of the previous contracting character in the
  267.      * string.
  268.      * @param ch the starting character of a contracting character token
  269.      * @param status the error code status.
  270.      * @return the previous contracting character's ordering.  Returns NULLORDER
  271.      * if the start of string is reached.
  272.      */
  273.             int32_t             prevContractChar(   UChar     ch,
  274.                                                     UErrorCode&  status);
  275.  
  276.     friend  class   RuleBasedCollator;
  277.     static  const   int32_t         UNMAPPEDCHARVALUE;
  278.  
  279.             Normalizer*            text;       // owning 
  280.  
  281.             VectorOfInt*        bufferAlias;
  282.             int32_t             swapOrder;  // for unmapped characters
  283.             int32_t             expIndex;
  284.             UnicodeString       key;
  285.     const   RuleBasedCollator*  orderAlias;
  286. };
  287.  
  288.  
  289. /**
  290.  * Get the primary order of a collation order.
  291.  * @param order the collation order
  292.  * @return the primary order of a collation order.
  293.  */
  294. inline int32_t
  295. CollationElementIterator::primaryOrder(int32_t order)
  296. {
  297.     order &= RuleBasedCollator::PRIMARYORDERMASK;
  298.     return (order >> RuleBasedCollator::PRIMARYORDERSHIFT);
  299. }
  300. /**
  301.  * Get the secondary order of a collation order.
  302.  * @param order the collation order
  303.  * @return the secondary order of a collation order.
  304.  */
  305. inline int32_t
  306. CollationElementIterator::secondaryOrder(int32_t order)
  307. {
  308.     order = order & RuleBasedCollator::SECONDARYORDERMASK;
  309.     return (order >> RuleBasedCollator::SECONDARYORDERSHIFT);
  310. }
  311. /**
  312.  * Get the tertiary order of a collation order.
  313.  * @param order the collation order
  314.  * @return the tertiary order of a collation order.
  315.  */
  316. inline int32_t
  317. CollationElementIterator::tertiaryOrder(int32_t order)
  318. {
  319.     return (order &= RuleBasedCollator::TERTIARYORDERMASK);
  320. }
  321.  
  322. inline int32_t
  323. CollationElementIterator::getMaxExpansion(int32_t order) const
  324. {
  325.     return orderAlias->getMaxExpansion(order);
  326. }
  327.  
  328. inline bool_t
  329. CollationElementIterator::isIgnorable(int32_t order)
  330. {
  331.     return (primaryOrder(order) == 0);
  332. }
  333.  
  334. #endif
  335.